A.8 Extracting agenda information

Org provides commands to access agenda information for the command line in Emacs batch mode. This extracted information can be sent directly to a printer, or it can be read by a program that does further processing of the data. The first of these commands is the function org-batch-agenda, that produces an agenda view and sends it as ASCII text to STDOUT. The command takes a single string as parameter. If the string has length 1, it is used as a key to one of the commands you have configured in org-agenda-custom-commands, basically any key you can use after C-c a. For example, to directly print the current TODO list, you could use

     emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr

If the parameter is a string with 2 or more characters, it is used as a tags/TODO match string. For example, to print your local shopping list (all items with the tag ‘shop’, but excluding the tag ‘NewYork’), you could use

     emacs -batch -l ~/.emacs                                      \
           -eval '(org-batch-agenda "+shop-NewYork")' | lpr

You may also modify parameters on the fly like this:

     emacs -batch -l ~/.emacs                                      \
        -eval '(org-batch-agenda "a"                               \
                 org-agenda-span month                             \
                 org-agenda-include-diary nil                      \
                 org-agenda-files (quote ("~/org/project.org")))'  \
        | lpr

which will produce a 30-day agenda, fully restricted to the Org file ~/org/projects.org, not even including the diary.

If you want to process the agenda data in more sophisticated ways, you can use the command org-batch-agenda-csv to get a comma-separated list of values for each agenda item. Each line in the output will contain a number of fields separated by commas. The fields in a line are:

     category     The category of the item
     head         The headline, without TODO keyword, TAGS and PRIORITY
     type         The type of the agenda entry, can be
                     todo               selected in TODO match
                     tagsmatch          selected in tags match
                     diary              imported from diary
                     deadline           a deadline
                     scheduled          scheduled
                     timestamp          appointment, selected by timestamp
                     closed             entry was closed on date
                     upcoming-deadline  warning about nearing deadline
                     past-scheduled     forwarded scheduled item
                     block              entry has date block including date
     todo         The TODO keyword, if any
     tags         All tags including inherited ones, separated by colons
     date         The relevant date, like 2007-2-14
     time         The time, like 15:00-16:50
     extra        String with extra planning info
     priority-l   The priority letter if any was given
     priority-n   The computed numerical priority

Time and date will only be given if a timestamp (or deadline/scheduled) led to the selection of the item.

A CSV list like this is very easy to use in a post-processing script. For example, here is a Perl program that gets the TODO list from Emacs/Org and prints all the items, preceded by a checkbox:

     #!/usr/bin/perl

     # define the Emacs command to run
     $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";

     # run it and capture the output
     $agenda = qx{$cmd 2>/dev/null};

     # loop over all lines
     foreach $line (split(/\n/,$agenda)) {
       # get the individual values
       ($category,$head,$type,$todo,$tags,$date,$time,$extra,
        $priority_l,$priority_n) = split(/,/,$line);
       # process and print
       print "[ ] $head\n";
     }